<body>
Generic JCR decorator layer.
<p>
This package implements a generic decorator layer for the Content Repository
for Java technology API (JCR). This layer can be used to add various extra
functionality and responsibilities to existing JCR implementations without
having to modify or even access the original source code. The decorator layer
implemented by this package functions entirely on the JCR API level without
any dependencies to an underlying implementation.
<p>
This decorator layer implements the Decorator design pattern on a package
level for the entire javax.jcr package. A client only needs to decorate
a top level Repository instance, and the decorator layer will automatically
handle the decoration of all Session, Node, and other JCR objects acquired
using the decorated repository.

<h2>Usage of the decorator layer</h2>
<p>
To use the decorator layer, a client should first acquire a Repository
reference using whatever mechanism supported by the repository implementation
in use. Then the client needs to create a DecoratorFactory instance and use
it to decorate the repository. The resulting repository decorator can then
be used as a normal repository instance. All other decorator instantiation
will then be handled internally by the decorator layer using the given
decorator factory.
<p>
The following example code illustrates how the decorator layer is instantiated
and used.
<pre>
    // Acquire a repository instance normally
    Repository repo = ...;
    
    // Create the decorator layer
    DecoratorFactory factory = ...;
    Repository deco = factory.getRepositoryDecorator(repo);
    
    // Use the decorated repository via the normal JCR API
    Session session = deco.login();
    Node root = session.getRootNode();
    Node node = root.getNode(...);
    Property prop = node.getProperty(...);
</pre>
<p>
The diagram below shows the object instances created by default
by the above code.
<p align="center">
<img src="doc-files/instances.jpg">
</p>

<h2>Extending the decorator layer</h2>
<p>
The Factory design pattern used in the DecoratorFactory interface and the
default decorator classes makes it easy to extend the functionality of the
decorator layer. Specific decorator functionality can be added by subclassing
the default decorators included in this package and providing a custom
DecoratorFactory that uses these specific decorator classes instead of the
defaults.
<p>
For example, a decorator for mapping user accounts between authentication
realms could subclass the RepositoryDecorator and SessionDecorator classes
and override the login() and impersonate() methods with custom functionality.
The decorator implementation would also provide a customized DecoratorFactory
for creating a decorator layer that uses the user account mapping
functionality. The layer can then be wrapped on top of an existing
repository implementation.
<p>
See the org.apache.jackrabbit.cache and org.apache.jackrabbit.trace packages
for examples of such decorator implementations.
</body>
